/*
 * JSObject.java - ScriptME
 * 
 * Copyright (c) 2009 Cesar Henriques <cesar at alttab.com.ar>.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the GNU Lesser Public License v2.1
 * which accompanies this distribution, and is available at
 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 * 
 * Based on FESI Project
 * 
 * Contributors:
 * 	Jean-Marc Lugrin - initial API and implementation
 * 	Cesar Henriques <cesar at alttab.com.ar> - J2ME Porting and Extensions
 */
package org.scriptme.ecmascript.jslib;

import java.io.Reader;

/**
 * Interface used for interfacing the FESI EcmaScript interpreter with Java
 * code. Based and largely compatible with the Netscape JavaScript to Java
 * interface.
 * <P>
 * This interface is exported by FESI objects, it is not intended or useful for
 * user objects to extend this interface.
 * <P>
 * Non function objects need not implement any specific interface, FESI using
 * introspection to discover their properties. Function objects must implement
 * JSFunction.
 */
public interface JSObject {

	/**
	 * Call the specified EcmaScript method of this object.
	 * 
	 * @param methodName
	 *            the method name
	 * @param args
	 *            the args
	 * 
	 * @return The result of the evaluation (unwrapped if required)
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public Object call(String methodName, Object args[])
			throws JSException;

	/**
	 * Evaluate a string with this object as the 'this' object. Consider the
	 * string being a main program, not allowing the return statement.
	 * 
	 * @param s
	 *            the s
	 * 
	 * @return The result of the evaluation (null if no value returned,
	 *         unwrapped if required)
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public Object eval(String s) throws JSException;

	/**
	 * Evaluate a Reader stream with this object as the 'this' object. Consider
	 * the stream being a main program, not allowing the return statement.
	 * 
	 * @param r
	 *            the r
	 * @param d
	 *            the d
	 * 
	 * @return The result of the evaluation (null if no value returned,
	 *         unwrapped if required)
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public Object eval(Reader r, String d) throws JSException;

	/**
	 * Evaluate a string with this object as the 'this' object. Consider the
	 * string as a function, allowing the return statement.
	 * 
	 * @param s
	 *            the s
	 * 
	 * @return The result of the evaluation (null if no value returned,
	 *         unwrapped if required)
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public Object evalAsFunction(String s) throws JSException;

	/**
	 * Evaluate a Reader stream with this object as the 'this' object. Consider
	 * the stream as a function, allowing the return statement.
	 * 
	 * @param s
	 *            the s
	 * @param names
	 *            the names
	 * @param values
	 *            the values
	 * 
	 * @return The result of the evaluation (null if no value returned,
	 *         unwrapped if required)
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	// abstract public Object evalAsFunction(Reader r, String d) throws
	// JSException;

	/**
	 * Evaluate a string with this object as the 'this' object. Consider the
	 * string as a function, allowing the return statement. Passing the
	 * specified parameters (names and values must have the same length)
	 * 
	 * @param s
	 *            The string to evaluate
	 * @param names
	 *            the names of the parameters
	 * @param values
	 *            the values of the parameters
	 * @return The result of the evaluation (null if no value returned,
	 *         unwrapped if required)
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public Object evalAsFunction(String s, String[] names,
			Object values[]) throws JSException;

	/**
	 * Evaluate a Reader stream with this object as the 'this' object. Consider
	 * the stream as a function, allowing the return statement. Passing the
	 * specified parameters (names and values must have the same length)
	 * 
	 * @param name
	 *            the name
	 * 
	 * @return The result of the evaluation (null if no value returned)
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	// abstract public Object evalAsFunction(Reader r, String d, String []
	// names, Object values[]) throws JSException;
	/**
	 * Get the named property of this object.
	 * 
	 * @param name
	 *            The name of the property to get
	 * @return The value of the property (unwrapepd if required)
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public Object getMember(String name) throws JSException;

	/**
	 * Get the indexed property of this object (useful for arrays).
	 * 
	 * @param index
	 *            the index
	 * 
	 * @return The value of the property (unwrapped if required)
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public Object getSlot(int index) throws JSException;

	// This Netscape function is not implemented
	// public static JSObject getWindow(Applet applet) throws JSException;

	/**
	 * Delete a named property of this object.
	 * 
	 * @param name
	 *            the name
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public void removeMember(String name) throws JSException;

	/**
	 * Set the value of a named property of this object.
	 * 
	 * @param name
	 *            the name
	 * @param value
	 *            the value
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public void setMember(String name, Object value)
			throws JSException;

	/**
	 * Set a property by index value. Useful for arrays.
	 * 
	 * @param index
	 *            the index
	 * @param value
	 *            the value
	 * 
	 * @throws JSException
	 *             the JS exception
	 * 
	 * @exception JSException
	 *                For any error during interpretation
	 */
	abstract public void setSlot(int index, Object value) throws JSException;

	// FESI extension

	/**
	 * Get the global object of the interpreter.
	 * 
	 * @return the global object
	 */
	abstract public JSGlobalObject getGlobalObject();
}
